---
description: 'How to use Environment Variables in Nitric projects'
---

# Environment Variables

Nitric sets a number of environment variables to help you manage your project. These variables are available in the cloud, build, and run environments.

## System Environment Variables

If you are running your project in the cloud, build, or the run environment, Nitric provides prefixed Environment Variables, which you can find in the table below.

| Name               | Description                                                                                                                                                                                                                   |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NITRIC_STACK_ID    | The Stack ID of the project. Example: `coolkat-gcp-4c0wg0hg`                                                                                                                                                                  |
| NITRIC_ENVIRONMENT | The Environment that the app is running on. The value can be either `cloud` (for deployed in the cloud), `run` (for stacks running in nitric run), or `build` (for stack code running during the deployment gathering phase). |

## Application Environment Variables

To use environment variables locally and in your deployed projects, you can create a file named `.env`. When running your project locally using `nitric start` the environment variables will be made available to your application. When running your project using `nitric run` and `nitric up`, the service is built into an image with the environment variables added at build time. An `.env` file might look like this:

```text label:.env
API_URL=http://this.is/a/test-url
```

If you wish to use an environment variable file that is in a different location, you can point to the file using the `--env-file` or `-e` flag.

```bash
nitric start --env-file ./config/.env.local

nitric up -e ./config/.env.cloud
```

## CI/CD Pipelines

Environment variables will also be pulled from a `.env` file when deploying your projects in a CI/CD environment, however, most CI/CD platforms provide options for using sensitive values. You can take a look at our CI/CD guides [here](/guides?tags=CI/CD) to see individual recommendations for each platform's workflow configurations.

## When should I use Secrets instead?

You should use cloud secrets over environment variables for services when you are using sensitive values and/or you require dynamic secret rotation or updates. Beyond this, you should be using Cloud Secrets when:

- **Your secret needs to be rotated dynamically**: Cloud secret managers support automatic rotation. This ensures your services always retrieve the latest secrets without redeployment.
- **You need access control & audit logging**: Cloud secret managers provide fine-grained access control (e.g., IAM policies) and track access logs, enhancing security and compliance.
- **Your secret contains sensitive configuration values**: Environment variables may be exposed in process lists, logs, or debugging tools. Secret managers keep values encrypted and only accessible at runtime.
- **Your secret is shared across multiple services**: If multiple services need access to the same credentials, cloud secrets prevent duplication and simplify management.
- **You want to avoid redeployment for secret changes**: Environment variables require redeployment to update secrets, whereas cloud secret managers allow dynamic retrieval and updates at runtime.
